/*
 * Licensed to Jasig under one or more contributor license
 * agreements. See the NOTICE file distributed with this work
 * for additional information regarding copyright ownership.
 * Jasig licenses this file to you under the Apache License,
 * Version 2.0 (the "License"); you may not use this file
 * except in compliance with the License.  You may obtain a
 * copy of the License at the following location:
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
package com.baijia;

import com.baijia.authentication.handler.exception.AuthenticationException;
import com.baijia.authentication.principal.Credentials;
import com.baijia.authentication.principal.Service;
import com.baijia.ticket.TicketException;
import com.baijia.validation.Assertion;
/**
 * @title CentralAuthenticationService
 * @desc Passport核心校验流程 
 * @author caoliang
 * @date 2015年12月4日
 * @version 1.0
 */
public interface CentralAuthenticationService {

    /**
     * 根据认证信息，生成TGT
     * 
     * @param 用户登录信息
     * @return TGT字符串
     * @throws 生成TGT流程无法完成时，抛出AuthenticationException 
     */
    String createTicketGrantingTicket(Credentials credentials)
        throws AuthenticationException,TicketException;

    /**
     * 为一个注册的service生成ST
     * 
     * @param 身份认证通过后，生成的TGT
     * @param 注册的service
     * @return ST字符串
     * @throws 生成ST流程无法完成时，抛出TicketException 
     */
    String grantServiceTicket(String ticketGrantingTicketId, Service service)
        throws AuthenticationException,TicketException;

    /**
     * 
     * @param 身份认证通过后，生成的TGT
     * @param 注册的service
     * @param 认证信息
     * @return ST字符串
     * @throws 生成ST流程无法完成时，抛出TicketException on if the ticket could not be created.
     */
    String grantServiceTicket(final String ticketGrantingTicketId,
        final Service service, final Credentials credentials)
        throws AuthenticationException,TicketException;

    /**
     * 验证ST是否和service关联并且合法
     * 
     * @param 认证流程上一步生成的ST字符串
     * @param 和ST相关联的service
     * @return 验证ST通过后，返回登录身份信息
     * @throws 验证ST流程无法完成时，抛出AuthenticationException
     */
    Assertion validateServiceTicket(final String serviceTicketId,
        final Service service) throws AuthenticationException,TicketException;

    /**
     * 销毁登录凭证TGT，登出时调用
     * 
     * @param TGT
     */
    void destroyTicketGrantingTicket(final String ticketGrantingTicketId);
}
